# Integration

Integration Actions are used within a workflow design to leverage advanced programmability features. These actions can enable workflows to interface with external systems and/or applications.

# .Net Code Action

Action Function: The .Net Code Action allows for ad-hoc code to be ran from within the workflow without the need for a full custom action to be developed.

Action Outputs:

[blank] – The default output for the action if successful

Action Error – The code threw a runtime exception

Compile Error – An error occurred when compiling the code

Additional outputs are available as set by the “Return Values” property

Action Properties:

Label

This property designates the name of the action or step as shown within the workflow design.

Properties:

Use these fields to configure the properties for the action:

Language

Specifies the language of the code. Options are C# and Visual Basic (VB.Net)

Code

A rich text editor with syntax highlighting for the code. Properties to set are:

Source Code: The source code to be executed. Code is configured as a class to be instantiated and the method which will be called.

Outputs can be null, a string, or an array of strings.

Class Name: The class name to instantiate at run time

Method: The method of the class to be invoked at run time

Additional tools are available to validate the code. The Validate button will compile the code immediately and will indicate the compiler output results in the Compile Output window.

References (optional)

Any DLL dependencies needed by the code

Return Values (optional)

Any additional possible outputs returned from the code

# Database Action

Action Function: The Database Command activity is used to communicate with a data source. Data sources can be SQL or Data Provider based. If the query returns results as part of a record set, this action will retrieve the value of the first column of the first row of the records set as a string, or a SQL tabular result can optionally be converted and stored into an XML variable automatically without specialized SQL knowledge.

Action Outputs:

Successful – indicates the action successfully executed the SQL query against the designated data source without error
Unsuccessful – indicates that an error occurred while trying to execute the SQL query against the designated data source
No Data – indicates that the query returned no result

Query Validator:

The Database Command action provides a wizard style interface to quickly configure queries for a given data source, including tools to leverage workflow values during the design process to streamline the process of properly querying data sources. Queries can be constructed which reference workflow values and may be tested without requiring the workflow to be executed.

The wizard requires that values have already been configured in the action properties for specifying the data source. Once the data source is specified in the action properties, to access the Query Validator, right click the action and select from the context menu, “Query Validator”.

An example usage scenario is provided below.

Set a registered data source.

Access the Query Validator

From the query validator window presented, enter a test query, and select “Test Query”

To build a query with workflow values and validate the query with test values, update the query to contain workflow values and select “Refresh Test Values”.

This will display a list of workflow references found in the query and allow for setting of test values for the query.

Provide test values and select “Test Query” to validate the query results.

Once the query is complete, select “Save and Close”. The query will be copied into the database action “Query” property.

Action Properties: The Database Get String activity is configured by specifying appropriate values for the various settings in the Action Properties panel. The Action Properties panel for a selected Database Get String action is accessed by selecting the Action Properties tool in the Tool Bar or by selecting Action Properties option from the right-click menu for the Database Get String activity. The specific Action Properties fields available for Database Get String actions are grouped into related sections as follows:

Label

This property designates the name of the action or step as shown within the workflow design.

Properties:

Use these fields to configure the functionality for this action:

Database *(required)

This property is used to select the source of the database to be queried, and offers a drop-down menu with the following options:

Registered Data Source – indicates that the target database will be selected from a list of existing data sources, as defined in the Administration, System Management, External Data Sources screen. Additionally, “Data Providers” may be referenced by name. Data providers are accessed from Administration, System Management, Providers.
SPE – indicates the target data source will reside in the Service Process Engine (SPE) database
Service Catalog – indicates the target data source will reside in the Service Catalog (SC) database
Custom Connection String – indicates the target data source will come from a custom ODBC connection string

Connection String / Data Source *(required – if using a Registered Data Source or a Custom Connection string)

This property is used either to identify an existing External Data Source to connect to when executing the query, or to define the literal connection string needed to connect to the database where the Query will be executed. (NOTE: If SPE or Service Catalog is selected in the preceding Database field, then this property may be blank, as the connection to those databases is already established through the system; in that case, you can skip this property and simply build the required Query in the subsequent field.)

If Registered Data Source was selected in the previous field, then enter the Name of the desired data source.

If Custom Connection String was selected in the previous Database field, then you will use this property to define the fully-qualified connection string to be employed when this action is executed, including the applicable Driver, Server, Database name, and valid credentials (ID and Password) for access. For example, a custom connection string setting would be entered into the text editor and formatted as follows:

Driver={SQL Server};Server=10.0.20.434;Database= ExternalHRData;Uid=Admin;Pwd=password123

Query *(required)

This property is used to define the actual SQL query or stored procedure, or property formatted Data Provider command to be executed against the designated data source for this action. The query property window will provide a rich text editor to provide the command to execute.

When building a SQL query to execute, you can either type the raw SQL directly into the text editor space, or you can build a SQL query that uses dynamic workflow values from the workflow instance. The “Workflow Data” button provides a menu of available workflow values to use within the query.

Once a valid SQL query or stored procedure has been entered in this window, select the Update button to save the setting and close the property window.

Note: See the “Query Validator” feature for a wizard based approach to building queries with workflow values.

Auto Xml

This property determines if the result should be converted to XML format which is compatible with the workflow designer. This removes the need to know the proper SQL commands to convert a tabular result as XML format.

Result

Specifies a string variable which will store the result from the query

XML Result (optional)

When “Auto Xml” is set to Yes, an XML variable can be selected to store the resulting table for processing in the workflow.

File Result

Specifies a target file variable to store formatted results

File Type

Selects the file type to store to the file result variable. Options are XLS and CSV.

Command Timeout

An optional time in seconds to wait for the command to execute

Empty Result Behavior

Provides options for output to follow when the SQL query result is empty.

Successful – Consider an empty result to be a success

No Data – Follow this output when the result is empty

Unsuccessful if setting XML – Follow this output if empty and setting XML

Escape Mode

Use As Synch Result

# Database Stored Procedure

Action Function: The Database Stored Procedure action simplifies calls to a Microsoft SQL Server stored procedure for registered external data sources.

Action Outputs: The action has the following outputs:

Failure – There was an error executing the stored procedure
Success – The stored procedure was executed without error

Action Properties: The action has the following configurable properties.

Label

This property designates the name of the action or step as shown within the workflow design.

Configure Stored Procedure

This property presents a new window to configure the stored procedure call.

Data Source – the select list of available registered external databases

Stored Procedure – stored procedures available to call

Parameter Name / Value table – presents the parameters for the stored procedure and allows for values to be set

Variable to place the query result

Allows a variable to be selected to store any result from the query

Command Timeout (Seconds)

Time in seconds to allow the stored procedure to run before failing

# Database Table

Action Function: The Database Table Update action allows for reading, inserting, updating or deleting rows of data, without requiring SQL knowledge. This action will work for Microsoft SQL Server databases registered as external data sources, and requires the table to have a unique identifier for read, update, and delete.

Action Outputs: The action has the following outputs:

Failure – There was an error executing the action
Success – The action executed without error

Action Properties: The action has the following configurable properties.

Label

This property designates the name of the action or step as shown within the workflow design.

Configure Fields

This property presents a new window to select a data source and specific table as well as specify the type of operation and particular values for fields as needed.

Data Source – the select list of available registered external databases

Table – A list of tables found in the selected database

Method – The action to perform: Read, Insert, Update, or Delete

Column Name / Value – presents the columns for the table allows for values to be set

To use the Read, Update or Delete action, the selected table must have a Unique Identifier column.

NOTE: This action does not support tables where one or more columns contains a space in the name. If the table you want to read, create, update or delete contains a column with a space in the name, please use the Database Action.

Variable for new table primary key output

For the Insert option, the newly created row’s unique identifier may be stored into a selected variable

Variable for error messages if any

A variable to store any error messages

Xml variable to place the query result if any

The XML variable to store a read row result

Command Timeout (Seconds)

Time in seconds to allow the stored procedure to run before failing

# Email Parser

Action Function: The Email Parser activity is used to load an email, based on an email Id generated from the Wait for Email action. This action then can set variables with values from the received email. The action can also save attachments from the email. As the “Wait for Email” action may receive many emails at once, considerations should be made to move the Email Parser action into a sub-workflow for processing of the given Email ID to process. Optionally, each set variable can be of type local to address potential issues with simultaneous multiple email processing.

Action Outputs: The action has the following outputs:

[Blank Output]– indicates the action successfully executed
Error – indicates that an error occurred while trying to execute

Action Properties: The Email Parser action has the following configurable properties.

Label

This property designates the name of the action or step as shown within the workflow design.

Email Id or Data

Specifies the source variable for the action, which contains either an Email Id or EML data file source. Email ID is usually the variable which was set by the prior Wait for Email action. Alternatively, to use a variable as the EML source, the variable should contain the full raw text of the EML file data. EML data files are commonly available from the Office 365 API or from AWS SES via S3.

From Address

Specifies the variable to store the “From Address” from the processed email.

From Name

Specifies the variable to store the “From Name” from the processed email.

Subject

This property is used to save the email subject into a variable.

Body as text

This property is used to save the email body into a variable as text.

Body as HTML

This property is used to save the email body into a variable as HTML.

Attachment Count

Sets the attachment count into the specified variable.

Attachment Save Location

This property is used to save email attachments to a local file system path.

EML Save Location

This property is used to save an email as an EML file format to a file system path.

# Encrypt String

Action Function: The Encrypt String action will encrypt string data in a reversible manner. The data will be stored encrypted in the application database and will also be shown encrypted when viewed from the workflow diagram details.

Action Outputs: The action has the following outputs:

Failure – some error occurred in executing the command
Success – The command was executed without error

Action Properties: The Encrypt String action has the following configurable properties.

Unencrypted Value

The value which will be encrypted.

Encryption Method *(required)

Specifies which encryption method will be used to encrypt the value contained in the property "Unencrypted Value".

Method 1: Accepts a limited ASCII character set, in the character range (32-127), as a valid input. Returns the encrypted value.
Method 2: Does not have a limitation on the ASCII character set. Returns the encrypted value.
Method 3: Updated method of encryption which is preferred over methods 1 and 2. Returns the encrypted value.
KMS: Key Management System. This is the preferred method of encryption and should be used whenever possible. Returns a globally unique identifier (GUID) which corresponds to the Id for the database row containing the encrypted value.

Results Variable *(required)

Specifies the variable for storing the result.

Error Variable

Specifies the variable for storing any error messages that occur during the actions execution.

# FTP Download File

Action Function: The FTP Download File action will a file from an FTP source to a local file. SSL is supported.

Action Outputs: The action outputs the following.

Success – The command was executed without error

Failure – An error occurred in executing the command

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the FTP connection.

Scenarios are managed from the Workflow Designer, Connector Configuration. “FTP.Config.xml”. To create a new scenario, select “New Scenario”, or select an existing scenario. Properties for the FTP connection are displayed in the configuration screen.

Server

Specifies the FTP server

Port

Specifies the FTP server port

Enable SSL

Determines if SSL is used

Source File Path

The fully qualified file name to download

Destination File Path

The fully qualified path and file name to store the downloaded file

Target File Variable

A file variable to store the downloaded file

Variable for Storing Error Message

A string variable to store error messages if the file download fails

# FTP File List

Action Function: The FTP File List action will return a list of files and folders from a specified FTP source.

Action Outputs: The action outputs the following.

Success – The command was executed without error

Failure – An error occurred in executing the command

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the FTP connection.

List Directory Type

Specifies the level of information to return from the directory list. Options are “List Directory Details” and “List Directory”

Directory

Specifies the directory to list

Variable for Output

The target variable to store the directory results

Variable for Storing Error Message

A string variable to store error messages if the file download fails

Xml Variable for Output

The target object variable to store the directory results

# FTP Upload File

Action Function: This action will upload a file to an FTP target server.

Action Outputs: The action outputs the following.

Success – The command was executed without error

Failure – An error occurred in executing the command

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the FTP connection.

Server

Specifies the FTP server

Port

Specifies the FTP server port

Enable SSL

Determines if SSL is used

Destination Directory

The target folder to place the uploaded file

Local File

The fully qualified path and file name of the source file

File Variable

The file variable to upload

Variable For Storing Error Message

A string variable to store error messages if the file upload fails

# Invoke Web Service

Action Function: The Invoke Web Service activity is used to invoke a web service from within a workflow process.

NOTE: While this action is provided in the list of standard Integration activities, it is intended to be used only when other options for connecting to remote systems are deemed less viable. For example, the Invoke Web Services action might suffice in certain circumstances, such as building a “one-off” web service call not intended for use across multiple workflows, or when facilitating simplistic interactions entailing the return of simple string data. In contrast, external connections that involve robust error handling, complex data sets, and/or multi-call interaction are typically much better suited for dedicated connector actions, or are candidates for new custom actions to be developed.

Some considerations and limitations of the Invoke Web Service action are below.

The action is generic, non-descriptive
It may require more complex setup and considerable understanding of the WSDL parameters for each use, which can be burdensome for workflow designers
There is limited opportunity for rich error support (e.g., service down and/or custom WSDL error responses). In contracts, often custom actions will be coded with logic to address known limitations or complexities with the environment or web service.
Requires strict WSDL support. Web Services are often custom developed, or do not follow a particular SOAP protocol.
No built-in help for the specifics and purpose of a given call and usage (e.g., parameters)
Minimal support for multi-stage Web Services usage (e.g., authenticate, make 2^nd call, make follow-up call, etc.), which then requires multiple actions for which may be one custom action.
Best suited to support only simple data element types (e.g., simple strings)
No opportunity to limit which parts of WSDL or WSDL parameters are implemented

Benefits of dedicated connectors and custom actions:

Visual icons to support the workflow builder
Provides for rich error feedback and logging
Opportunity to handle custom conditions (e.g., retry on custom errors)
Restricts usage to authorized actions and activity only (e.g., limit the web service endpoints and even limitations on the inputs as well)
Presents a simplistic view of the process being supported
Provides clearly noted inputs and outputs for the workflow designer
Provides self-describing documentation for the process supported (e.g., field level help)

If a dedicated connector is not available, and, if any substantial integration work and workflow design will be used with the third party system, then it is recommended that new custom actions are developed to support the integration.

Action Outputs:

[blank] – No error was detected from the invoked web service

Webservice Execution Failed – An error was encountered when invoking the Web Service

Action Properties:

Label

A label for the action in the diagram

Properties

Web Services Details

This property is used to select from the available web services defined with the “Settings, Web Services” within the Designer, and to specify inputs and outputs for the call.

Select a Web Service from the first list provided. Then, select a method from the “Service Method” list which shows all of the available methods to invoke.

After selecting a method, details about the method will be displayed to indicate the method signature, and parameters and types.

Once a method is selected, click “Bind” to be taken to a screen where each of the input values can be set as well as well as the target variable to store the web service response.

Runtime URL or Server

This property allows for the target URL to be defined at runtime

The list of existing Web Services available for use in a workflow is managed via the Web Services function under the Settings menu in the Designer main menu.

Selecting this menu item will open a separate window where you can add, edit or delete Web Service objects. This window also offers an Import function to import any previously configured Web Service definitions from another environment into the current one via an XML file. The management window will initially display a global list of any existing Web Services that have been declared in the current environment. Each declared Web Service object will be displayed on a separate row, with buttons provided to export, delete, or edit any existing Web Service definition, as needed.

To add a new Web Service to the current environment, click the “+ Add” button at the bottom left. This will display several fields where the new Web Service can be defined:

Name – display name for the new Web Service record to be available globally in the current environment
URL – target URL or web address to be accessed when executing this Web Service call
Description – optional text to describe or clarify the Web Service object being defined
Authenticated – checkbox to indicate whether any calls to this Web Service will require authentication
Login Name – Login ID or account to be used when connecting to the target system, if authentication is required; depending on the target system’s API, this value may be just and ID, or may require a full UPN value
Password – corresponding password for the Login ID used when connecting to the target system, if authentication is required
Domain Name – optional domain name for the Login ID used when connecting to the target system, if authentication is required

Once the information provided in these fields is complete and accurate, click Save to save the details and return to the list of Web Services. Upon clicking Save, the system will attempt to validate the new Web Service using the data provided. If connectivity access is confirmed, the new Web Service will now appear in the list. If the connection cannot be validated, an error message in red will display at the top right of the window, and the new Web Service will not be added to the list.

Once validated and saved, the new Web Service profile will be reflected in the list of existing Web Services seen in the initial management window. The existing items displayed in this management window will constitute the list of available Web Services that can be selected for use in an Invoke Web Service workflow action.

# Read Text File

Action Function: The Read Text File action will load a text file from the file system into a workflow text variable or XML variable. CSV files may be converted into XML variables when loaded.

Action Outputs: The action will output the below:

Failure – some error occurred in executing the action

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

Authentication Scenario

Specifies the name of the authentication scenario to use for impersonation while reading the file.

The name of the scenario document is “PMGIO.Config.xml". This can either be stored in the file system or in the database using the “Connector Configuration” from within the Workflow Designer.

An example configuration document is below. The “system” example provided will execute the command without impersonation.

<<ioconfig>
    <!-- Configure these scenarios with real domain user accounts -->
    <scenario name="test" username="pmgio_test" domain="PMGNETDEV" password="_ENCRYPTED_PASSWORD_HERE_"></scenario>
    <!-- leave the username attribute empty to use the Workflow Engine account for File IO -->
    <scenario name="system" username="" domain="" password=""></scenario>
</ioconfig>

File Path

Specifies the file path to be read

File is Delimited, e.g. (CSV)?

Specifies if the file has a delimiter

Delimiter

The delimiter character to use when processing the file

Column Names in First Row?

Specifies if the first row of the input file are column names

XML Schema File Path

An XML schema to use when processing the data

Variable For File Contents

Variable to store the processed results

# Run Program

Action Function: The Run Program action executes Microsoft Windows compatible programs, with optional identity impersonation, passing in parameters, and obtaining results from the command. The program will be executed from the workflow engine service directly as opposed to executing the called program in a separate process. The workflow engine runs as “SYSTEM” which may cause issues with the called program, despite impersonation. Alternatively, see the “Run Program with Proxy” action.

Action Outputs: The action will output either:

Error – some error occurred in executing the command

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

Config Source

Specifies where the credentials will be provided for impersonation.

Current Action – The credentials will be provided in the additional action properties

XML File – the scenario will be in the XML configuration. The name of the scenario document is “ExecuteAs.Config.xml". This can either be stored in the file system or in the database using the “Connector Configuration” from within the Workflow Designer.

An example configuration document is below. The “SYSTEM” example provided will execute the command without impersonation.

<actionconfig>
  <scenario name="SYSTEM">
    <domain></domain>
    <username></username>
    <password></password>
    <arguments></arguments>
    <waitseconds></waitseconds>
  </scenario>
  <scenario name="NewUserScript">
    <domain>MYDOMAIN</domain>
    <username>adminUser</username>
    <password>_ENCRYPTED_PASSWORD_HERE_</password>
    <filepath>C:\temp\newuser.vbs</filepath>
    <arguments>-d /logfile.txt</arguments>
  </scenario>
  <scenario name="NewMailboxScript">
    <domain>MYDOMAIN</domain>
    <username>adminUser</username>
    <password>_ENCRYPTED_PASSWORD_HERE_</password>
    <filepath>C:\temp\newmailbox.vbs</filepath>
    <arguments>-dxe /logfile.txt</arguments>
  </scenario>
  <scenario name="PMGAdmin">
    <domain>PMGNETDEV</domain>
    <username>Administrator</username>
    <password>_ENCRYPTED_PASSWORD_HERE_</password>
  </scenario>
</actionconfig>

Executable File Path

Specifies the file path for the command to run

Execution Arguments

Specifies the arguments for the command

Wait for Execution (Seconds)

Time to wait in seconds for the command to complete

Variable for Standard Output

Specifies the variable to store the command output (stdout)

Variable for Standard Error

Specifies the variable to store the command errors (stderr)

Variable for Exit Code

Specifies the variable to the store the exit code of the command

# Save Request Attachments

Action Function: This action will download a file from an SFTP source to a local file stored to the file system.

Action Outputs: The action will output either:

Failure – some error occurred in saving the attachments

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

Authentication Scenario

Specifies the name of the execution scenario which contains the credentials for saving the attachments.

Example scenario, PMGIO.Config.xml

<ioconfig>
  <!-- Configure these scenarios with real domain user accounts -->
  <scenario name="test" username="pmgio_test" domain="PMGNETDEV" password="_ENCRYPTED_PASSWORD_HERE_"></scenario>
  <!-- leave the username attribute empty to use the Workflow Engine account for File IO -->
  <scenario name="system" username="" domain="" password=""></scenario>
</ioconfig>

File Path

Overwrite: any files with matching names will be overwritten

Preserve: any files with matching names will not be overwritten

Variable for Output Message

A string variable to store any messages for errors when saving the attachments

# SFTP Download File

Action Function: This action will download a file from an SFTP source to a local file stored to the file system.

Action Outputs: The action will output either:

Success – The command was executed without error

Failure – An error occurred in executing the command

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the SFTP connection.

See SSL and SFTP Configuration Management to manage scenarios.

Server

Specifies the SFTP server

Port

Specifies the SFTP server port

Source File Path

The fully qualified file name to download

Destination File Path

The fully qualified path and file name to store the downloaded file

Target File Variable

A file variable to store the downloaded file

Variable for Storing Error Message

A string variable to store error messages if the file download fails

# SFTP Upload File

Action Function: This action will upload a file from the file system to an SFTP target server.

Action Outputs: The action will output either:

[blank] – The command was executed without error

Error – some error occurred in executing the command

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the SFTP connection.

See SSL and SFTP Configuration Management to manage scenarios.

Server

Specifies the SFTP server

Port

Specifies the SFTP server port

Destination Directory

The target folder to place the uploaded file

Local File

The fully qualified path and file name of the source file

File Variable

The file variable to upload

Variable For Storing Error Message

A string variable to store error messages if the file upload fails

# SFTP Delete File

Action Function: This action will delete a file from the SFTP server.

Action Outputs: The action will output either:

Success – The command was executed without error

Error – some error occurred in executing the command

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the SFTP connection.

See SSL and SFTP Configuration Management to manage scenarios.

File Path

The path and name of the file to be deleted

Variable For Storing Error Message

A string variable to store error messages if the action fails

# SFTP Rename File

Action Function: This action will rename a file on the SFTP server

Action Outputs: The action will output either:

Success – The command was executed without error

Error – some error occurred in executing the command

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the SFTP connection.

See SSL and SFTP Configuration Management to manage scenarios.

Source File Path

The path and name of the file to be renamed

Target File Path

The path and name of the new file name

Variable For Storing Error Message

A string variable to store error messages if the action fails

# Remote SSH Command

Action Function: This action will execute an SSH command via remote registered agents.

Action Outputs: The action will output either:

Failure – some error occurred in executing the command
Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

Remote Scenario

Specifies the remote scenario, managed from the Designer Menu Bar, Manage, Connector Configuration, ExecuteAs.Config.xml.

An example scenario is below.

<actionconfig>
    <scenario name="machineA">
        <!-- name:Specifies the name of the scenario to be used by the workflow action -->
        <relayServerCommMode>WebSocket</relayServerCommMode>
        <!-- Specifies the communications mode for the relay. If the node value is WebSocket, then WebSockets will be used for the connection. Otherwise, standard TcpClient is used. -->
        <useRelayServer>true</useRelayServer>
        <!-- When the node is “true”, specifies the connection will use a Relay Server, or if “false” or not present, then a direct TCP connection will be made. -->
        <proxyServer /><!-- Optional proxy server machine name or IP address -->
        <proxyPort /><!-- Optional proxy port to use -->
        <proxyUser /><!-- Optional proxy user if credentials are required -->
        <proxyDomain /><!-- Optional user domain for credentials if required -->
        <proxyPassword /><!-- Optional proxy password if required -->
        <relayConfig>
            <!-- NOTE: Multiple relayConfig nodes may be defined to specify a list of relays to try.This node specifies attributes for the relay server -->
            <ip>127.0.0.1</ip><!-- Specifies the machine name or IP address of the relay server -->
            <workflowPort>17001</workflowPort><!-- Specifies the network port of the Workflow Engine -->
            <retryDelayMs>1000</retryDelayMs><!-- Optional delay in milliseconds to retry a communication request -->
            <agentWaitMs>30000</agentWaitMs>
            <!-- Optional time in milliseconds to wait for a remote command to execute -->
        </relayConfig>
        <agentName>machineA</agentName>
        <!-- NOTE: multiple agentName nodes may be specified to establish a pool of agents to try to send commands -->
        <domain>DOMAIN</domain><!-- The domain name for the user to authenticate for the remote command -->
        <username>USERNAME</username><!-- The username to authenticate the remote command -->
        <password note="thisIsMethod2">Q…AA==</password>
        <!--The password of the remote user to authenticate the remote command -->
        <waitseconds>600</waitseconds>
        <!--The time to wait in seconds for the command to execute. -->
        <certName>Workflow Remote Agent Server</certName>
        <!-- The name of the certificate to be used when using TcpClient. The cert must be installed in the Personal folder for the local machine -->
        <authKey>qi…m</authKey> <!-- a shared secret key -->
    </scenario>
    <actionconfig>

Run Mode

This setting determines how the action will be executed.

New Process: The action will run within a separate execution scope, with the security context of the running service
New Process (As User): The action will run in as the user identity specified in the given scenario

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the SFTP connection.

See the SSH Command action Execution Scenario property documentation for more details

Username

Specifies the username credential. This property is overridden by the username specified in the execution scenario.

Password

Specifies the password credential. This property is overridden by the password specified in the execution scenario.

Server

Specifies the SFTP server

Port

Specifies the SFTP server port

Command Text

The command to execute

Variable for Output

Output from the SSH command will be stored to the specified variable

Variable for Storing Error Message

The variable in which to store the error message (if any).

Variable for Exit Status

The variable in which to store the exit status of the SSH command.

# SSH Command

Action Function: This action will execute an SSH command

Action Outputs: The action will output either:

Failure – some error occurred in executing the command

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

Execution Scenario

Specifies the name of the execution scenario which contains the credentials for the SFTP connection.

Example scenario configuration:

SSH.Config.xml

<sshconfigs>
  <sshconfig scenario="MyScenario1">
    <username>_username_</username>
    <password>_method2_encrypted_password_</password>
    <server>10.10.10.10</server>
    <port>22</port>
  </sshconfig>
  <sshconfig scenario="MyScenario2">
    <username>_username_</username>
    <password>_method2_encrypted_password_</password>
    <server></server>
    <port></port>
    <sshkey>_key_file_path_</sshkey>
  </sshconfig>
  <sshconfig scenario="MyScenario3">
    <username>_username_</username>
    <password>_method2_encrypted_password_</password>
    <server></server>
    <port></port>
    <sshkey>_method2_encrypted_key_</sshkey>
    <sshkeytype>string</sshkeytype>
  </sshconfig>
</sshconfigs>

Server

Specifies the SFTP server

Port

Specifies the SFTP server port

Command Text

The command to execute

Variable for Output

Output from the SSH command will be stored to the specified variable

# Upload CSV to Database

Action Function: The Upload CSV to Database action will process a CSV file and upload the file data into a target Database Table

Action Outputs: The action will output the below:

Failure – some error occurred in executing the action

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

Database *(required)

This property is used to select the target database for the data upload, and offers a drop-down menu with the following options:

Registered Data Source – indicates that the target database will be selected from a list of existing data sources, as defined in the Administration, External Data Sources
SPE – indicates the target data source will reside in the PMG Workflow database
Service Catalog – indicates the target data source will reside in the Service Catalog database
Custom Connection String – indicates the target data source will come from a custom ODBC connection string

Connection String / Data Source *(required – if using a Registered Data Source or a Custom Connection string)

This property is used either to identify an existing External Data Source to connect to for the data upload or to define the literal connection string needed to connect to the database where the data will be uploaded.

NOTE: If you selected either SPE or Service Catalog in the preceding Database field, then you can leave this property blank, as the connection to those databases is already established through the system.

If Registered Data Source was selected in the previous field, then you would simply enter the Name of the desired data source, as defined in Administration, External Data Sources. Once the appropriate Name has been entered, select the Update button to save the setting and close the Connection String property window.
If Custom Connection String was selected in the previous Database field, then this property is used to define the fully-qualified connection string to be employed when this action is executed, including the applicable Driver, Server, Database name, and valid credentials (ID and Password) for access. For example, a custom connection string setting would be entered into the text editor and formatted as follows:

Driver={SQL Server};Server=10.0.20.434;Database=ExternalHRData;Uid=Admin;Pwd=password123

Once the appropriate External Data Source Name or custom connection string value is entered in the property window, select the Update button to save.

File Variable

A file variable containing the CSV file

File Path

The file path of the source CSV file

Table Name

The name of the database table to store the file data

Truncate target table

Sets whether to delete all the data in the target table initially

Separator Character

If uploading a CSV file, use this field to specify the character that separates columns of data, e.g., comma, semicolon, pipe

Text Qualifier Character

Character that surrounds text data that contains the separator character, e.g., double- or single-quote

Escape Character

Character that escapes the text qualifier character when it is contained within column data, e.g., backslash

Variable For Imported Row Count

Variable to store the number of data rows imported

# Upload JSON to Database

Action Function: The Upload JSON to Database action will process a JSON document and upload the data into a target database table, providing mapping options to convert the data

Action Outputs: The action will output the below:

Failure – some error occurred in executing the action

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

JSON String

The source JSON document to use for the data upload

Database

This property is used to select the source of the database to be queried, and offers a drop-down menu with the following options:

Registered Data Source – indicates that the target database will be selected from a list of existing data sources, as defined in the Administration, External Data Sources
SPE – indicates the target data source will reside in the PMG Workflow database
Service Catalog – indicates the target data source will reside in the Service Catalog database
Custom Connection String – indicates the target data source will come from a custom ODBC connection string

Connection String / Data Source *(required – if using a Registered Data Source or a Custom Connection string)

This property is used either to identify an existing External Data Source to connect to for the data upload.

If Registered Data Source was selected in the previous field, then you would simply enter the Name of the desired data source, as defined in Administration, External Data Sources. Once the appropriate Name has been entered, select the Update button to save the setting and close the Connection String property window.
If Custom Connection String was selected in the previous Database field, then this property is used to define the fully-qualified connection string to be employed when this action is executed, including the applicable Driver, Server, Database name, and valid credentials (ID and Password) for access. For example, a custom connection string setting would be entered into the text editor and formatted as follows:

Driver={SQL Server};Server=10.0.20.434;Database=ExternalHRData;Uid=Admin;Pwd=password123

Once the appropriate External Data Source Name or custom connection string value is entered in the property window, select the Update button to save.

Table Name

The name of the database table to store the file data

Data Root

Specifies the parent node in dot notation to use as the data root in the source JSON document for the data to be uploaded

Columns

Defines the data mapping for the data to be uploaded. The property screen allows for any number of entries for each needed table “Column Name” and the “Path” for the source of the column data from the JSON document.

An example screen is below.

For each path, use dotted notation to specify the location of the data, such as “spec.brand”.

Truncate target table

Sets whether to delete all the data in the target table initially

Variable For Imported Row Count

Variable to store the number of data rows imported

# Upload XML to Database

Action Function: The Upload XML to Database action will process a source XML document and upload the data into a target database table, providing mapping options to convert the data.

Action Outputs: The action will output the below:

Failure – some error occurred in executing the action

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

XML String

The source XML document to use for the data upload

Database

This property is used to select the source of the database to be queried, and offers a drop-down menu with the following options:

Registered Data Source – indicates that the target database will be selected from a list of existing data sources, as defined in the Administration, External Data Sources
SPE – indicates the target data source will reside in the PMG Workflow database
Service Catalog – indicates the target data source will reside in the Service Catalog database
Custom Connection String – indicates the target data source will come from a custom ODBC connection string

Connection String / Data Source *(required – if using a Registered Data Source or a Custom Connection string)

This property is used either to identify an existing External Data Source to connect to for the data upload.

If Registered Data Source was selected in the previous field, then you would simply enter the Name of the desired data source, as defined in Administration, External Data Sources. Once the appropriate Name has been entered, select the Update button to save the setting and close the Connection String property window.
If Custom Connection String was selected in the previous Database field, then this property is used to define the fully-qualified connection string to be employed when this action is executed, including the applicable Driver, Server, Database name, and valid credentials (ID and Password) for access. For example, a custom connection string setting would be entered into the text editor and formatted as follows:

Driver={SQL Server};Server=10.0.20.434;Database=ExternalHRData;Uid=Admin;Pwd=password123

Once the appropriate External Data Source Name or custom connection string value is entered in the property window, select the Update button to save.

Table Name

The name of the database table to store the file data

Data Root

Specifies the parent node in XPath notation to use as the data root in the source XML document for the data to be uploaded. For example, the below XPath would search for the '/Report_Data/Report_Entry' node to consider as the node containing the repeating table data to be mapped using the 'Columns' property.

/Report_Data/Report_Entry

Columns

Defines the data mapping for the data to be uploaded. The property screen allows for any number of entries for each needed table “Column Name” and the “XPath” for the source of the column data from the source document.

An example screen is below.

Truncate target table

Sets whether to delete all the data in the target table initially

Variable For Error Message

Variable to store any error messages from the activity

Variable For Imported Row Count

Variable to store the number of data rows imported

# Wait for Database Value

db-wait-for-value

Action Function: The Wait for Database activity is used to run a database query against a designated data source on a recurring basis, until a specified output is returned. The activity will continue to run the query and poll for results at regular intervals until an expected output is returned, at which time the workflow would follow a corresponding output path in the workflow design. Each individual output value defined in the Action Properties panel for this activity must also indicate whether or not it should serve as a completion-maker for the current step. The Wait for Database action will continue to process and run the designated query at the specified time interval until an output designated as a completion-maker is returned.

Action Outputs: In addition to any specific output values defined in the Action Properties panel, the Wait for Database activity can output the following:

Error – an error occurred while trying to retrieve query results from the database

Action Properties:

Label

A label for the action in the diagram

Properties

Database

This property is used to select the source of the database to be queried, and offers a drop-down menu with the following options:

Registered Data Source – indicates that the target database will be selected from a list of existing data sources, as defined in the Administration, System Management, External Data Sources screen. Additionally, “Data Providers” may be referenced by name. Data providers are accessed from Administration, System Management, Providers.
SPE – indicates the target data source will reside in the Service Process Engine (SPE) database
Service Catalog – indicates the target data source will reside in the Service Catalog (SC) database

Custom Connection String – indicates the target data source will come from a custom ODBC connection string

Connection String/Data Source

If Registered Data Source was selected in the previous field, then enter the Name of the desired data source.

Driver={SQL Server};Server=10.0.20.434;Database= ExternalHRData;Uid=Admin;Pwd=password123

Query

Once a valid SQL query or stored procedure has been entered in this window, select the Update button to save the setting and close the property window.

Check Interval

This property is used to specify the frequency or time interval after which the Query should be re-run on a recurring basis. The Query will be run each time this interval is reached, until a designated completion-maker output value is returned.

To set the Check Interval period, click into the text field, and enter the applicable timeframe in Days, Hours, Minutes, and Seconds in the following format – (D.HH:MM:SS).

Retry on Error

This property is a Yes/No drop-down field, set to “Yes” by default, used to indicate whether or not the system should try to re-run the Query if an error is returned. If set to “No,” and a result of “Error” is ever returned, then the workflow will follow any corresponding Error output path within the workflow design without re-running the Query again.

However, if set to “Yes,” the Query would continue to be re-run on the applicable time interval set in the previous Check Interval field, even after an output of “Error” was returned on a prior attempt. This would allow the action to continue polling a database for designated outputs, and to follow an Error output at the same time, if needed.

Follow Output

This property is used to specify the number of times the applicable output path(s) from this Wait for Database action should be followed, when a matching result is returned. The field offers a drop-down menu with the following two options:

• Every Time – indicates that a matching output path should be followed every time the Query is executed, even if the results are repeated

• When Output Changes – indicates that a matching output path should only be followed when the Query results are different from the previous execution

Outputs

This property is used to define the specific output values (besides the standard “Error” output) that this Wait for Database action will be looking for when polling the Query results.

• Output – specifies the output value to be returned when the Query is executed

• Completion Maker? – Yes/No drop-down menu to designate whether or not this output value should serve as a completion-maker for this Wait for Database activity. If set to “Yes,” this step will be marked as completed and left behind in the workflow when the applicable output path is followed; otherwise, if set to “No,” the activity will continue to process even after this output is returned.

If multiple Outputs are needed, you can select the Add Row button and repeat the steps above as needed.

Once all applicable Outputs have been defined, select the Update button to save the settings and close the property window.

# Write Text to File

Action Function: This action creates a text file with the specified text.

Action Outputs: The action will output:

Failure – some error occurred in executing the command

Success – The command was executed without error

Action Properties:

Label

A label for the action in the diagram

Properties

Authentication Scenario

Specifies the name of the authentication scenario to use for impersonation while creating the file. If blank, or “system”, the action will run in the workflow engine context.

Example scenario, PMGIO.Config.xml

<ioconfig>
  <!-- Configure these scenarios with real domain user accounts -->
  <scenario name="test" username="pmgio_test" domain="PMGNETDEV" password="_ENCRYPTED_PASSWORD_HERE_"></scenario>
  <!-- leave the username attribute empty to use the Workflow Engine account for File IO -->
  <scenario name="system" username="" domain="" password=""></scenario>
</ioconfig>

File Path

The file path to write

Text Content

The text to write

Write Mode

Overwrite: The text will replace any existing text

Append: The text will be appended to any existing text

Preserve: Do not replace the file if it exists

Label

A label for the action in the diagram

Properties

Authentication Scenario

Specifies the name of the authentication scenario to use for impersonation while creating the file.

Example scenario, PMGIO.Config.xml

<ioconfig>
  <!-- Configure these scenarios with real domain user accounts -->
  <scenario name="test" username="pmgio_test" domain="PMGNETDEV" password="_ENCRYPTED_PASSWORD_HERE_"></scenario>
  <!-- leave the username attribute empty to use the Workflow Engine account for File IO -->
  <scenario name="system" username="" domain="" password=""></scenario>
</ioconfig>

File Path

The file path to write

Text Content

The text to write

Write Mode

Overwrite: The text will replace any existing text

Append: The text will be appended to any existing text

Preserve: Do not replace the file if it exists

# PowerShell

The PowerShell action allows for execution of PowerShell scripts. The action properties are as follows.

Name

Provides for a friendly custom name for the action within the diagram

Label

Provides for an additional text label for the action within the diagram

Run Mode

This setting determines how the PowerShell will be executed.

InProc: The PowerShell will run within the workflow engine process, the same as other workflow actions.

New Process: The PowerShell will run within a separate execution scope, with the security context of the running service

New Process (As User): The PowerShell will run in as the user identity specified in the given scenario

Execution Scenario

Specifies the execution scenario, managed from the Designer Menu Bar, Manage, Connector Configuration, ExecuteAs.Config.xml.

An example scenario is below.

<actionconfig>
    <scenario name="UserA">
        <domain>DOMAIN</domain>
<!-- The domain name for the user to authenticate -->
        <username>USERNAME</username>
<!-- The username to authenticate the remote command -->
        <password note="thisIsMethod2">Q…AA==</password>
<!--The password of the user to authenticate the command -->
    </scenario> 
<actionconfig>

Script

The Script property contains the script to run on the remote server. The editor provides a PowerShell syntax aware editor as below. The script supports accessing and setting PMG workflow variables, which then effectively provides a PowerShell data bus for any scripts ran within the workflow.

Similarly, Workflow Object variables can be set directly from PowerShell. The below illustrates two methods working with Workflow Object variables.

#declare a new anonymous object $newObj, and then set the Workflow Object variable named $WFObj.
$newObj = @{}
$newObj.Prop = "val"
$WFObj = $newObj | ConvertTo-Json

#directly set a Workflow Object
$WFObj = @{}
$WFObj.Prop = "val"

Script Error Handling: By default, PowerShell does not treat script errors as a failure of the script. For example, the below script will continue execution past the 'divide by zero' error. This script would run to the end and would follow 'Successful' in the workflow.

$val = 5/0
get-date

To change the behavior of PowerShell script error handling, use the $ErrorActionPreference variable as below. This change will cause PowerShell to consider the 'divide by zero' error as fatal, stop the script execution, and the workflow action will follow out as 'Unsuccessful'.

$ErrorActionPreference = "Stop"
$val = 5/0
get-date

Variable for Information

Optional string variable to capture “Information” level pipeline details

Variable for Error

Optional string variable to capture “Error” level pipeline details

Action Outputs

This action will output one of the following

Successful – The PowerShell was able to execute (with or without PowerShell script errors)

Unsuccessful – The Relay Framework encountered some issue in attempting to transmit or receive the information for the requested PowerShell script.

← Human Activities Workflow Variables →